x
Skip to main content

MacOS Installation Guide for Stirling PDF

Stirling PDF can be run on macOS via the dedicated dmg installer here, or the JAR file which can be found here.

Prerequisites:​

  • Java 17 or 21 (21 preferred)
    • Install via Homebrew: brew install openjdk@21

Running Stirling PDF​

  1. Open Terminal
  2. Navigate to the folder containing the JAR: 
    cd /path/to/folder/containing/jar
  3. Run the JAR file: 
    java -jar Stirling-PDF.jar

For convenience, you can create a simple script:

  1. Create a file named run-stirling.sh and add the following contents: 
    #!/bin/bash    
    cd /path/to/folder/containing/jar
    java -jar Stirling-PDF.jar
  2. Make it executable: 
    chmod +x run-stirling.sh
  3. Run it with: 
    ./run-stirling.sh

Optional Dependencies​

Install these via Homebrew to enable additional features like advanced document conversion or PDF compression:

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies as needed
brew install openjdk@21          # Required
brew install qpdf                # PDF compression
brew install --cask libreoffice  # Document conversion
brew install tesseract           # OCR functionality
brew install tesseract-lang      # Additional OCR languages
brew install poppler             # PDF to HTML conversion
pip3 install weasyprint          # URL to PDF conversion
pip3 install unoserver           # File to PDF conversion

For Tesseract OCR, add to config/settings.yml (generated once you first run the jar):

system:
  tessdataDir: /usr/local/share/tessdata

Quick Troubleshooting​

  • Java not found? Add to ~/.zshrc: 
    export PATH="/usr/local/opt/openjdk@21/bin:$PATH"
  • Verify installations with: [command] --version (e.g., java --version)
  • LibreOffice issues? Ensure no LibreOffice processes are running
  • Need help? Visit GitHub Issues

Starting unoserver alongside Stirling PDF​

To ensure that unoserver is running alongside Stirling PDF, you need to start it with the following command:

unoserver --port 2003 --interface 0.0.0.0

You can add this command to your startup script or systemd service file to ensure it starts automatically with Stirling PDF.